        VADV-PHP DOCUMENTATION                                       12-19-2004
        ----------------------

        INTRODUCTION
        ------------

        Welcome to the new world of VADV-PHP!

        The goal of this project is to provide a web interface for the aging
        software of Virtual Advanced. Virtual Advanced (VADV) is a powerful
        bulletin board system that was created by Roland de Graaf in 1996. It is
        the successor to the popular Virtual Bulletin Board System (VBBS). VBBS
        and VADV are both DOS based programs (also available is an OS/2 version)
        which require third party programs for them to be accessible by Internet
        users. VADV-PHP will add a new avenue for users to reach the BBS and
        interact by allowing them to simply use their web browsers.

        PHP is a powerful open source scripting language that does server-side
        processing. This means that all calculations and computations done by
        PHP are performed by the web server, so the users only see the results
        of these processes.

        VADV-PHP does all the necessary processes on the web server directly
        with the BBS, so all information displayed to your users is in real-
        time.
        

        REQUIREMENTS
        ------------

        In order to use VADV-PHP with your BBS, you must meet the following
        requirements.

            - You must have Virtual Advanced v2.1 for DOS or OS/2 installed.

            - You must have a working web server installed along with PHP
              v4.2.x or above.

            - The web server must have some type of access to the BBS files,
              whether it be directly or through a network. You configure the
              method in the VADV-PHP_CONFIG.PHP file.

            - VADV-PHP was written so that Register_Globals in PHP.INI can be
              turned OFF. This is highly recommended for security's sake
              (that it is turned OFF).

              It also uses "sessions", so make sure that your sessiondata
              directory is valid.

              VADV-PHP can be used if "magic quotes" are turned on or off. It is
              recommended that you turn them off though.


        INSTALLATION
        ------------

        The installation procedure is very easy and very quick no matter which
        platform you are installing it on! It basically only involves copying
        files to a directory of your choice and editing a few files.

        Follow the following steps below to install VADV-PHP.

            1. Create a new directory that is accessible by your web server and
               also has access to process .PHP files.

            2. Unarchive all of the files contained the VADV-PHP zip file into
               the directory you created above and maintain the directory
               structure. There will be a few subdirectories created.

            3. One of the files that were unarchived in the /include directory is
               called VADV-PHP_CONFIG.PHP. Open this file in a text editor. This
               file is a PHP script and contains variables that you may want to
               edit. This file is documented further below.

            4. Try to access the INDEX.PHP file using your web browser. It
               should load, if not then check your VADV-PHP_CONFIG.PHP
               configuration.


        CONFIGURATION
        -------------

        The configuration of VADV-PHP is done by editing the file
        VADV-PHP_CONFIG.PHP. It is a PHP script, so the formatting of the file
        must follow PHP standards in order for it to compile and run. I also
        suggest that all variables use single quotations in this file since some
        configuration options use paths and backslashes.

        After the initial configuration, you may edit this configuration file
        from VADV-PHP itself. It is listed in the vconfig utilities.

        All of the variables in the VADV-PHP_CONFIG.PHP file belong to the array
        $CONFIG. Be sure to not change any part of the variable names.

        The configuration variables will be discussed below in detail. The
        variable references below excludes the array format and only the element
        name is displayed to save space and reduce confusion.

            'telnet'

                Set this variable to your BBS's telnet address (if you have
                one). Do NOT put a telnet:// prefix.

            'hostname'

                This variable is only used if the web server and the BBS are on
                separate computers. If the web server and BBS are on the same
                computer, then set this variable to blank ('').

                If the web server and BBS are on separate computers, then this
                variable allows you to set the UNC name or IP address of the
                BBS machine. For example, if the web server is on the computer
                named "WEB" and the BBS is on the computer named "BBS" then you
                would set this variable to 'BBS'. This would set all file paths
                to point to \\BBS\<path to files>. The web server would need
                permission to access the files on the BBS computer.

            'filehost'

                This variable is like the "hostname" variable above. It should
                be set to the UNC or IP address of the computer that the BBS
                file area files resides on. If the web server and BBS file area
                files are on the same computer, then set this to blank ('').

            'bbsdir'

                This variable is simply the path name of your main BBS directory
                on the BBS computer. Often it is the default of 'C:\VA', but if
                your BBS is in a different directory, then set it here.

                This variable works with the hostname variable above to determine
                the correct path the web server needs to access the BBS files.

            'syspass'

                If enabled, this option will require that the SysOp enter the
                BBS's system password when attempting to execute any of the
                VConfig scripts.

            'webmaster'

                This variable is an email address of the webmaster or SysOp of
                the BBS and/or web server. This email address will be used if
                a user clicks on a link to email the webmaster.

            'usersl'

                This variable needs to be set to the BBS security level you wish
                to give the web users. Usually you give the web users a security
                level less than or equivalent to a validated user on your BBS.
                If the security level is set too low then the users may not be
                able to access anything, or if it is set too high you may
                inadvertently give the web users SysOp access!

            'useraccflags'

                This variable is set to give the web users whatever access flags
                you wish for them to have. Often this is just left blank, unless
                you wish to give web users access to certain sections of the BBS
                or restrict them from certain sections.

            'userage'

                This variable sets the "age" of the web user. This is useful if
                you do not want web users (who can be of any age) to access
                adult areas of your BBS.
                
            'purgetime'
            
                This variable can be set so you can control how long a user's
                account can be idle before it is overwritten by a new user.
            
            'purgeminlevel'
            
                This variable is the user security level that begins the range
                of users that can be deleted based on inactivity.
            
            'purgemaxlevel'
            
                This variable is the user security level that ends the range of
                users that can be deleted based on inactivity.

            'newuserreq'

                You may specify what information is required from new users
                during registration. This variable takes an integer value which
                is derived from adding up the values of each field to require.
                For a list of the values, see the configuration file.

            'banned'

                You are able to ban certain user accounts from logging into
                VADV-PHP. This is useful for system accounts, QWK accounts, guest
                user accounts, or to just keep unruly users from having full
                access.

            'refresh'

                You can tell VADV-PHP to refresh certain pages (currently the
                index.php and who.php pages) after a number of seconds expire.
                This is useful if you want to monitor your system using
                VADV-PHP.

            'fileupload'

                You can enable or disable the ability of users to upload files
                to the file area. If you do not have any need for file uploads,
                it is recommended that you leave it disabled. Please read the
                section in this document for more information about file
                uploads.

            'newslist'
            'postitnt'
            'sysnews'

                These options allow you to turn on or off various AT2k scripts.
                You can have these scripts running on your telnet BBS, but have
                them disabled on the web BBS.


        FILE UPLOADING
        --------------

        VADV-PHP supports file uploading in two ways. First, if a user has
        a high enough security level, they may attach files to outgoing emails.
        Secondly, users may upload files to the file area.

        PHP requires a few configuration entries in the PHP.INI file to be
        changed before uploading may occur. By default, uploads are turned off
        and VADV-PHP will not allow users to upload since it would fail if they
        tried. There is a section in PHP.INI called File Uploads. It contains
        three settings and two of them must be changed in order for uploads to
        work:

            'file_uploads' must be turned ON (it is OFF by default)
            'upload_tmp_dir' must be set to a valid directory

        When these are set, then uploads may occur. The third setting 'upload_
        max_filesize' can be set to a maximum filesize that can be transferred.
        VADV-PHP uses this value as the largest filesize it will allow to be
        uploaded. PHP defaults to '2M' which would mean 2MB.

        Other information regarding file uploads: VADV-PHP mimics VADV as much
        as possible in the way it handles itself. It handles uploads in the
        same manner. If you turn on 'secure uploads' in VConfig, then all files
        uploaded to the file area will be placed into the \VA\SYSOP directory
        until you (the SysOp) reviews the files and places them into an
        appropriate database. Currently, you must review these files within
        the BBS itself. This is done from the file area menu, by typing '/REV'.
        If 'secure uploads' is turned off, then the file that is uploaded will
        immediately appear in the database in which it was uploaded to. If your
        system is local and you trust ALL users, then you can set 'secure
        uploads' to be off. Otherwise, turn it on for security reasons!

        Email attachments are controlled by the user's security level. The
        email attachment security setting is found in VConfig's main
        configuration (screen three).


        EMAIL ALL USERS
        ---------------

        As the SysOp, you can email multiple users on your BBS using VADV-PHP.
        This is done by either using security levels or user flags as its
        criteria. The script post-email.php handles the sending of emails. To
        do this, login as the SysOp, goto Check Your Email, then click on
        Send Email.

        Email All Users:
            To: all

        Email Users Based on Security Level:
            To: all > 20        - This emails all users with SL higher than 20.
            To: all < 100       - This emails all users with SL lower than 100.
            To: all = 25        - This emails all users with SL equal to 25.

        Email Users Based on User Flags:
            To: all ! F         - This emails all users with user flag 'F'.
            To: all $ A         - This emails all users with access flag 'A'.


        OPTIONAL FEATURE INSTALLATION
        -----------------------------

        Image Thumbnail Viewer - You can view thumbnails of GIF, JPEG or PNG
        files in the file area. This requires that GD2 is installed in your
        PHP installation. If you installed PHP using the .ZIP archive, then
        you already have GD2. You just need to activate it:

            1. Open PHP.INI with an editor.
            2. Search for EXTENSION_DIR
            3. Set the extension directory to the one created on your system. If
               you installed PHP into C:\PHP, then the directory is
               C:\PHP\EXTENSIONS. If you do not have this directory, then
               download the ZIP archive of PHP and install it.
            4. Search for PHP_EXIF.DLL
            5. You should find the line that looks like:
                   ;extension=php_exif.dll
               Remove the semicolon from the start of the line to uncomment it.
            6. Search for PHP_GD2.DLL
            7. You should find the line that looks like:
                   ;extension=php_gd2.dll
               Remove the semicolon from the start of the line to uncomment it.
            8. Save PHP.INI and exit. That's all there is to activate this.

        New Web User Registration Text File - You can create a new user message
        that will appear at the top of the registration form. This is similar to
        the BBS's NEWUSER.TXT that is shown before a user creates an account on
        the BBS. Create a new text file in your \VA\TXT directory called
        "NWEBUSER.TXT". Just type your message and save. You can put HTML into
        this file to make your message appear like you want.


        DEVELOPMENT / TESTING
        ---------------------

        VADV-PHP is developed under Windows 2000 using Maguma Studio. I use
        the Xitami web server for all initial testing. Beta testing is done
        on Windows 2000/XP and Windows 9x operating systems under the Apache
        and IIS web servers.
        
        It is unknown if VADV-PHP will work under a *NIX system.

        If you would like to help develop or help test VADV-PHP, then please
        email me.


        SUPPORT / TROUBLESHOOTING
        -------------------------

        If you have any problems, then please contact me! Since this project is
        so new, I have not had much feedback concerning problems or suggestions.
        This is also my first project using PHP, so expect some unorthodox
        methods.

        Email:   steve@at2k.org
        Website: http://www.vadvphp.com

        VADV-PHP Mailing List - Please join the VADV-PHP mailing list! Visit the
        website for more information.


        OTHER INFORMATION
        -----------------

        View the file LICENSE.TXT for information concerning copyrights and
        licensing.

        AT2k, Aspect Technologies Copyright  Steve Winn 1996-2004. All Rights
        Reserved.

        VADV-PHP Copyright  Steve Winn 2002-2004. All Rights Reserved.

        VADV, Virtual Advanced Copyright  Roland De Graaf 1995-1997. All Rights
        Reserved.